~ chicken-core (chicken-5) /manual/Using the interpreter
Trap1[[tags: manual]]2[[toc:]]34== Using the interpreter56CHICKEN provides an interpreter named {{csi}} for evaluating Scheme programs7and expressions interactively.89=== Writing Scheme scripts1011Since UNIX shells use the {{#!}} notation for starting scripts,12anything following the characters {{#!}} is ignored, with the exception of the special13symbols {{#!optional, #!key, #!rest}} and {{#!eof}}.1415The easiest way is to use the {{-script}} option like this:1617 % cat foo18 #! /usr/local/bin/csi -script19 (import (chicken port)20 (chicken process-context))21 (print (eval (with-input-from-string22 (car (command-line-arguments))23 read)))2425 % chmod +x foo26 % ./foo "(+ 3 4)"27 72829The parameter {{command-line-arguments}} is set to a list of the30parameters that were passed to the Scheme script. Scripts can be compiled31to standalone executables.3233CHICKEN supports writing shell scripts in Scheme for other platforms as well,34using a slightly different approach. The first example would look like35this on Windows:3637 C:>type foo.bat38 @;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %939 (import (chicken port)40 (chicken process-context))41 (print (eval (with-input-from-string42 (car (command-line-arguments))43 read)))4445 C:>foo "(+ 3 4)"46 74748Like UNIX scripts, batch files can be compiled. Windows batch scripts do not49accept more than 8 arguments.5051Since it is sometimes useful to run a script in the interpreter without actually executing it52(for example to test specific parts of it), the option {{-ss}} can be used as an alternative to {{-script}}.53{{-ss PATHNAME}} is equivalent to {{-script PATHNAME}} but invokes {{(main (command-line-arguments))}}54after loading all top-level forms of the script file. The result of {{main}} is returned as the exit status55to the shell. Any non-numeric result exits with status zero:5657 % cat hi.scm58 (define (main args)59 (print "Hi, " (car args))60 0)61 % csi -ss hi.scm you62 Hi, you63 % csi -q64 #;1> ,l hi.scm65 #;2> (main (list "ye all"))66 Hi, ye all67 068 #;3>6970When {{csi}} is started with the {{-script}} option, the feature identifier {{chicken-script}}71is defined, so can conditionally execute code depending on whether the file is72executed as a script or normally loaded into the interpreter, say for debugging purposes:7374<enscript highlight=scheme>75#!/bin/sh76#| demonstrates a slightly different way to run a script on UNIX systems77exec csi -s "$0" "$@"78|#79(import (chicken process-context))8081(define (main args) ...)8283(cond-expand84 (chicken-script85 (main (command-line-arguments)))86 (else))87</enscript>8889See also the documentation for the {{-ss}} option above.9091You can also have a look at [[/writing portable scripts]].929394=== Toplevel commands9596The toplevel loop understands a number of special commands:9798; ,? : Show summary of available toplevel commands.99100; ,c : Show call-trace items of the most recent error101102; ,ch : Clears stored expression results of previously evaluated expressions.103104; ,d EXP : Describe result of evaluated expression {{EXP}}.105106; ,du EXP : Dump contents of the result of evaluated expression {{EXP}}.107108; ,dur EXP N : Dump {{N}} bytes of the result of evaluated expression {{EXP}}.109110; ,e FILENAME : Runs an external editor to edit the given {{FILENAME}} (see below for more information).111112; ,exn : Describes the last exception that occurred and adds it to the result history (it can be accessed using the {{#}} notation).113114; ,f N : Select call-trace item with the given number, where the number {{0}} indicates the last item in the trace115116; ,g NAME : Returns the value of the local variable with the given name (which may be a symbol or string); you don't have to give the complete name - {{,g}} will return the first variable that matches the prefix given117118; ,h : Shows all previously evaluated expression results.119120; ,l FILENAME ... : Load files with given {{FILENAME}}s121122; ,ln FILENAME ... : Load files and print result(s) of each top-level expression.123124; ,m MODULENAME : switches the "current module" to {{MODULENAME}}, so expressions will be evaluated in the context of the given module. To switch back to toplevel, use {{#f}} as a MODULENAME. In compiled modules, only exported bindings will be visible to interactively entered code. In interpreted modules all bindings are visible.125126; ,p EXP : Pretty-print evaluated expression {{EXP}}.127128; ,q : Quit the interpreter.129130; ,r : Show system information.131132; ,s TEXT ... : Execute shell-command.133134; ,t EXP : Evaluate form and print elapsed time.135136; ,x EXP : Pretty-print macroexpanded expression {{EXP}} (the expression is not evaluated).137138You can define your own toplevel commands using the {{toplevel-command}}139procedure (see [[Module (chicken csi)]]).140141142=== Getting error information143144Interpreted code has some extended debugging information available145that can be used to locate errors and obtain information about the146lexical environment that was effective at the point of error. When an147error occurs in an evaluated expression, a "call trace" is printed -148the list of calls up to the error location. Note that this does not149follow a stack model: it is merely a list of recently made procedure150calls where the last one in the list is (probably) the call of151whatever procedure was executing before the error happened. You can152use the {{,c}} command to show the call-trace of the last153error. Depending on whether compiled or interpreted code was executing154and how much debugging information is available, the call trace shows155trace-buffer entries of the following shape:156157 <frame-number>:<environment?> <mode> <procedure-name> <form>158159{{<frame-number>}} gives the number of the call-trace entry, counting160from zero and beginning with the most recent entry. If a {{[]}}161follows the frame-number, then this frame contains the lexical162environment in effect when that procedure call took place. {{<mode>}}163is optional and is either {{<syntax>}} or {{<eval>}} indicating164whether this trace-buffer entry represents a syntax-expansion or an165evaluation and is not given for compiled code. {{<form>}} is also only166available for interpreted code and shows the procedure call167expression, possibly following the name of the procedure containing168the call expression.169170If the trace-buffer entry contains lexical environment information171then the complete environment of the call site is shown.172173Use {{,f}} to select a frame by number, if you want to inspect the174lexical environment of an earlier frame. The {{,g}} command lets you175retrieve the value of a local or lexical variable from the currently176selected frame. Note that the variables are renamed to simplify the177variable lookup done internally by the interpreter.178179=== Running an external editor180181The {{,e}} command runs the editor given by:182183* The parameter {{editor-command}} in the {{(chicken csi)}} module should184 return a string naming185 an external editor and defaults to {{#f}}, which means no editor is currently186 selected (so the following alternatives are tried).187188* The contents of the environment variables {{EDITOR}} or {{VISUAL}}.189190* If the environment variable {{EMACS}} is set, the editor chosen is {{emacsclient}}.191192* In a desparate attempt to find an editor, {{vi}} is used.193194=== History access195196The interpreter toplevel accepts the special object {{#INDEX}} which197returns the result of entry number {{INDEX}} in the history list. If198the expression for that entry resulted in multiple values, the first199result (or an unspecified value for no values) is returned. If no200{{INDEX}} is given (and if a whitespace or closing paranthesis201character follows the {{#}}, then the result of the last expression is202returned. Note that the value that {{#INDEX}} stands for is an expression,203not a literal, and so is implicitly quoted, so204205 #;1> 123206 123207 #;2> '(1 2 #)208209will not return the result you expected.210211=== Auto-completion and editing212213On platforms that support it, it is possible to get auto-completion of214symbols, history (over different {{csi}} sessions) and a more215feature-full editor for the expressions you type using the216[[/eggref/5/breadline|breadline]] egg by Vasilij Schneidermann.217It is very useful for interactive use of csi. See the egg's218documentation on how to set it up. If readline is not available on219your system consider using the self-contained220[[/eggref/5/linenoise|linenoise]] egg221instead. It should work on almost any system but is not as222feature-rich as readline (e.g. it lacks reverse-i-search and223auto-completion).224225226=== csi command line format227228{{csi {FILENAME|OPTION}}}229230where {{FILENAME}} specifies a file with Scheme source-code. If the231extension of the source file is {{.scm}}, it may be omitted. The232runtime options described in [[Using the compiler#Compiler command line format|Compiler command line format]] are also available233for the interpreter. If the environment variable {{CSI_OPTIONS}}234is set to a list of options, then these options are additionally passed235to every direct or indirect invocation of {{csi}}. Please note that236runtime options (like {{-:...}}) can not be passed using this method.237The options recognized by the interpreter are:238239; -- : Ignore everything on the command-line following this marker. Runtime options ({{-:...}}) are still recognized.240241; -i -case-insensitive : Enables the reader to read symbols case insensitive. The default is to read case sensitive (in violation of R5RS). This option registers the {{case-insensitive}} feature identifier.242243; -b -batch : Quit the interpreter after processing all command line options.244245; -e -eval EXPRESSIONS : Evaluate {{EXPRESSIONS}}. This option implies {{-batch}}, {{-no-init}} and {{-quiet}}, so no startup message will be printed and the interpreter exits after processing all {{-eval}} options and/or loading files given on the command-line.246247; -p -print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.248249; -P -pretty-print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{pretty-print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.250251; -D -feature SYMBOL : Registers {{SYMBOL}} to be a valid feature identifier for {{cond-expand}} and {{feature?}}.252253; -h -help : Write a summary of the available command line options to standard output and exit.254255; -I -include-path PATHNAME : Specifies an alternative search-path for files included via the {{include}} special form. This option may be given multiple times. If the environment variable {{CHICKEN_INCLUDE_PATH}} is set, it should contain a list of alternative include pathnames separated by {{:}} (UNIX) or {{;}} (Windows).256257; -K -keyword-style STYLE : Enables alternative keyword syntax, where {{STYLE}} may be either {{prefix}} (as in Common Lisp) or {{suffix}} (as in DSSSL). Any other value is ignored.258259; -n -no-init : Do not load initialization-file. If this option is not given and the file {{$HOME/.csirc}} exists, then it is loaded before the read-eval-print loop commences.260261; -no-parentheses-synonyms : Disables list delimiter synonyms, [..] and {...} for (...).262263; -no-symbol-escape : Disables support for escaped symbols, the |...| form.264265; -w -no-warnings : Disables any warnings that might be issued by the reader or evaluated code.266267; -q -quiet : Do not print a startup message. Also disables generation of call-trace information for interpreted code.268269; -r5rs-syntax : Disables the CHICKEN extensions to R5RS syntax. Does not disable non-standard read syntax.270271; -s -script PATHNAME : This is equivalent to {{-batch -quiet -no-init PATHNAME}}. Arguments following {{PATHNAME}} are available by using {{command-line-arguments}} and are not processed as interpreter options. Extra options in the environment variable {{CSI_OPTIONS}} are ignored.272273; -sx PATHNAME : The same as {{-s PATHNAME}} but prints each expression to {{(current-error-port)}} before it is evaluated.274275; -ss PATHNAME : The same as {{-s PATHNAME}} but invokes the procedure {{main}} with the value of {{(command-line-arguments)}} as its single argument. If the main procedure returns an integer result, then the interpreter is terminated, returning the integer as the status code back to the invoking process. Any other result terminates the interpreter with a zero exit status.276277; -setup-mode : When locating extensions, search the current directory first. By default, extensions are located first in the ''extension repository'', where {{chicken-install}} stores compiled extensions and their associated metadata.278279; -R -require-extension NAME : Equivalent to evaluating {{(import NAME)}}. {{NAME}} may be given in list notation, e.g. {{"(srfi 1)"}}.280281; -v -version : Write the banner with version information to standard output and exit.282283284---285Previous: [[Getting started]]286287Next: [[Using the compiler]]